/**
 * @file str_utils.h
 * @brief Macros of the string utils functions.
 * @date Out-2011
 * @author Leonardo Lino 2101101
 * @author Joaquim Ferreira 2101104
 * @version 1.0
 */

#ifndef STR_UTILS_H
#define STR_UTILS_H

/** @brief This global integer variable (G_continue) will be used to treat the signal breakpoint to free all the resources.*/
extern int G_continue;
/** @brief This global integer variable (G_proc_lines) will contain the number of processed lines.*/
extern int G_proc_lines;

/** @brief This structure will contain the word and the counter of the word.*/
typedef struct
{
  char *word; /** @brief The word pointer*/
  int count; /** @brief The counter of the word */
} FREQ_WORD_T;

/**
 * @brief Function that check the word lenght and for invalid characters.
 * @fn int validateWord(char *word)
 * @param word The pointer to the string (parameter word).
 * @return Return 1 if the lenght of the word is greater or equals 2 and there isn't any invalid characters, otherwise return 0.
 */
int validateWord (char *word);

/**
 * @brief Function that show a line with a given word, if the type is WORD_OPTION or send words to a hashtable, if the type is FREQ_OPTION.
 * @fn void getLinesOrWords (char *filename, char *word, int type)
 * @param filename A pointer to the filename string.
 * @param arg A generic pointer (will be used in the word option and the freq option).
 * @param type The type of option, WORD_OPTION or FREQ_OPTION.
 * @return Return a generic pointer.
 */
void *getLinesOrWords (char *filename, void *arg, int type);

/**
 * @brief Function that convert a string to lower case.
 * @fn char *strlower (char *str)
 * @param str The pointer to the string.
 * @return Returns the pointer to the string.
 */
char *strlower (char *str);

/**
 * @brief Function that trim the last character from a word. Used to remove some invalid characters.
 * @fn char *trimWord(char *str)
 * @param str The pointer to the string.
 * @return Return a pointer to the new string.
 */
char *trimWord (char *str);

/**
 * @brief This function outputs a message for invalid number of parameters.
 * @fn void invalid_param(char *arg, char * param)
 * @param arg A pointer to the string (parameter argv).
 * @param param A pointer to the string (parameter).
 * @return Nothing to return.
 */
void invalid_param (char *arg, char *param);

/**
 * @brief Function that add a key and a value to the hashtable or update an existent value.
 * @fn add_word_hasht(HASHTABLE_T *word_hasht, char *word)
 * @param word_hasht The pointer to the hashtable.
 * @param word The pointer to the word string.
 * @return Nothing to return.
 */
void add_word_hasht (HASHTABLE_T * word_hasht, char *word);

/**
 * @brief Function that convert a hashtable to a linkedlist and show the word histogram (--freq option).
 * @fn void convert_show_histogram(HASHTABLE_T *f_word_hasht)
 * @param f_word_hasht The pointer to the hashtable.
 * @return Nothing to return.
 */
void convert_show_histogram (HASHTABLE_T *word_hasht);

/**
 * @brief Function that compares the number order from two words counters used in linkedlist.
 * @fn int counter_compare(FREQ_WORD_T *f_word1, FREQ_WORD_T *f_word2)
 * @param f_word1 The pointer to the struct FREQ_WORD_T.
 * @param f_word2 The pointer to the struct FREQ_WORD_T.
 * @return Return < 0 if f_word2->count < f_word1->count, > 0 if f_word2->count > f_word1->count and if f_word2->count == f_word1->count,  return < 0 if f_word1->word < f_word2->word, 0 if f_word1->word == f_word2->word and > 0 if f_word1->word > f_word2->word.
 */
int count_word_compare (FREQ_WORD_T * f_word1, FREQ_WORD_T * f_word2);

/**
 * @brief Function that free the allocated memory from the word struct and the struct.
 * @fn void free_freq_word(FREQ_WORD_T *f_word)
 * @param f_word The pointer to the struct FREQ_WORD_T.
 * @return Nothing to return.
 */
void free_freq_word (FREQ_WORD_T * f_word);

/**
 * @brief Function that concatenate two strings, one with the path, then the slash '/' and then the other with the directory name or the filename.
 * @fn char *path_cat(char *str1, char *str2)
 * @param str1 The pointer to the string (path name).
 * @param str2 The pointer to the string (filename).
 * @return A string with the full path and filename.
 */
char *path_cat (char *str1, char *str2);

/** 
 * @brief Function that will return the number of digits that a given integer number has.
 * @fn int num_digits(int number)
 * @param number The integer number.
 * @return Return the number of digits that a given integer number has. 
 */
int num_digits (int number);

#endif /* STR_UTILS_H */
